------------------------------------------------------------------------------- **** XTENDER ZX81 EMULATOR -- Very Preliminary Version 0.14 **** by Carlo Delhez, November 1991 ------------------------------------------------------------------------------- This file is in 80-column ASCII format. Use an ASCII editor to read the contents, import into your favourite word processor or copy directly to your printer (approximately 10 pages @ 60 lines/page). ------------------------------------------------------------------------------- NOTE: This programme is in a VERY early stage of development. Please keep this in mind when reading the manual and running the programme. If you are interested, look out for improved future versions! All remarks and suggestions regarding XTender are welcome. PROGRAMME DESCRIPTION XTender is - stated very accurately - a Z80 Emulator in a Sinclair ZX81 environment, written for MS/DOS machines with a standard graphics adapter (Hercules, CGA, PCjr, EGA, MCGA or VGA). The Z80 Emulator is able to execute programmes written in the Z80 machine code language. The ZX81 environment includes the original ZX81 ROM and additionally caters for `hardware compatibility' (such as keyboard reading, screen output control and redirecting of signals originally heading for devices such as tape and lineprinter). The Z80 Emulator and the ZX81 environment are joined in a single block of 8086 machine code, which - as a whole - shall be referred to as ZX81 Emulator, and is named XTender. REGISTRATION XTender is distributed as ShareWare. You are allowed to make copies for other people, provided you copy ALL the files and do NOT make changes in any one of these files. Use XTender for a trial period of 21 days and then delete the files if you don't like to use the programme. However, if you DO like to use XTender, please express your appreciation and support my efforts by becoming a REGISTERED user. You will then receive a nicely printed copy of this manual, you will be informed about new releases, and can update to a more recent version for a small fee to cover my costs. Registration also includes conversion of your programmes from tape to disk, free technical support by the author and the possibility to obtain a custom-made version of XTender to suit your specific hardware configuration. Also, it may be nice to set up an XTender Users Group to exchange programmes and ideas, or to create a large ZX81 programme libarary. All initiatives are welcome! To become a registered XTender user, send a cheque or money order worth Hfl 50 (Holland), UK pound sterling 16 (United Kingdom) or US $ 30 (elsewhere) made payable to J.L.Delhez, plus a note stating your name, address and computer specs to me (address at the bottom of this document). The most recent version of XTender on a 3.5" DS/DD floppy (3M) and a printed copy of this manual will be dispatched you (sorry, no 5.25"). NOTE: Special permission needs to be requested from the author before distributing XTender via Bulletin Boards or equivalent public domain software distribution services. However, this text file may be distributed freely without special permission. COMPATIBILITY Since the original ZX81 ROM in Z80 code is included (with only a few minor changes, of no interest for ordinary use) almost complete software compatibility is guaranteed. Almost, since only some VERY specific software can obviously NOT be emulated: programmes using either standard or non-standard input/output ports (e.g. the ear/mic-lines and lines connected to external hardware devices not available on the PC such as sound-generators or EPROM programmers; note however that the keyboard and printer input-lines are emulated correctly), and programmes taking over the interrupt vector (e.g. Hi-Res and ZX81 sprite programmes, although the characterset can be redefined in the usual way) are NOT (yet) supported by XTender. Apart from these exceptional applications, ANY programme running on the ZX81 should ALSO run on XTender. COMPARISON To name just a few advantages of XTender with respect to the ZX81: safe housing in a well-stabilized computer (none of the tricky business with wobbling RAM packs), full 64k RAM available (including POKEable ROM and 8-16k area), reliable and fast data-storage (no more tapes!), the ZX81 display file can be moved to any part of memory without a crash, machine code can also be executed in the top 32k of memory (on the ZX81 only the bottom 32k could be used), easy screen invert option, etc. etc. A disadvantage may be operation speed. On slow machines, the processor emulation becomes quite dull. On fast machines, the speed becomes far too high for reasonable operation. Therefore, TWO versions of XTender are supplied: a speed optimized version for slow machines and a user-variable-speed version for fast machines. More about this in the next section. SPEED CONSIDERATIONS As mentioned in the previous section, XTender might be too slow or too fast on your machine. As a solution, two versions of XTender are included. Let me first try to explain with an example why one programme with fixed speed would be insufficient. I am developing XTender on a 33 MHz 386dx machine. On this machine, XTender spends about 30% of total time for printing the display using the 18.2 Hz interrupt, so 80% is left for Z80 emulation. Compared to the ZX81 itself, which spends 75% of the time for writing the display, this is not much. But taking into account the high speed of the processor, this is quite a lot. Nonetheless, the speed of the emulation amounts to 400% (slow version) or 600% (fast version) of the original ZX81 in SLOW mode. Now lets see what happens if you work on a slower machine, say 2 times slower. Automatically, the computer spends twice the time on the screen display, i.e. 60% of the total time. Only 40% of the time is left for Z80 emulation, but in this time it can also do only half of the work the other processor could do. Thus, the total speed with respect to the first case becomes 40%/80%/2 = 25%, i.e. with HALF the processor speed, the emulator gets FOUR times slower (yielding an effective speed of 100% and 150% respectively). Generally, you would like to have emulation speed proportional to the processor speed of your computer. This means that you must cut down on screen output so that it is restricted to, say, 30% of total time. This is in fact what XTender does in the first second after start-up. It tests processor speed and tries to adapt the screen output frequency to (18.2/N) Hz, with N an integer (1,2,3,4,...) in order that less time is spent by the display interrupt. The number N is stored at ZX81 address 37, so you increase or decrease the screen frequency at will by POKEing this address. All the above is nice for speeding up XTender, but what if you want to slow it down on a fast machine? The screen frequency cannot be raised above 18.2 Hz, so another process is needed for slowdown. The smoothest slowdown is obtained by delaying each separate Z80 instruction. This is done in the slow version of XTender and the delay can be changed by the user (ZX81 address 23). More information about these facilities can be found in the section `Speeding Up and Slowing Down'. STARTING XTENDER For running XTender, you need an MS/DOS machine with a standard graphics adapter (Hercules, CGA, PCjr, EGA, MCGA or VGA) and about 256k of free memory to store the programme and the required work space. Note that your MS/DOS version is not important (or should not be!). As said earlier, the disk contains two versions of XTender. These are called XTENDERF.COM and XTENDERS.COM. The first is the fastest version and should be used on slow machines. The second one is not speed-optimized, hence slower. However, this one has the possibility to slow emulation down considerably and should be used on (very) fast machines. The user must determine by experience which one works best on his machine. My experience indicates that up to a 12 MHz AT or 16 MHz 386sx, the fast version works best. For faster machines, the slow version seems better. To start the programme, simply type XTENDERF or XTENDERS (whichever you prefer) at the DOS prompt. This will start up XTender. First, the screen will go black and stay black during one second. This is the processor speed test. Next, the screen should become completely white. Depending on the speed of your computer, you will see some flashes or some weird characters and text, but eventually the famous inverse-K-cursor should appear and XTender is ready for use. Xtender tries to determine what video card you have installed (by looking at the current video mode) in order to make a destinction between Hercules and non-Hercules. In Hercules, only a small portion of the display will be used, in all other modes, the ZX81 screen occupies almost the entire display. If you have CGA emulation on your Hercules card and want to use it with XTender, make sure you do NOT start XTender with video mode 7 (you can see this, for example, with Norton SysInfo). KEYBOARD FACILTITIES A problem for many users may be the keyboard: the ZX81 works with single keypress entries (e.g. pressing 'P' gives 'PRINT'). For the time being, you will need a ZX81 or ZX81 manual near your PC to look up all the special key presses for keywords, punctuation marks, functions and graphics. In the future, a help facility will be provided by XTender (under CTRL-F1). The default ZX81 screen color is black characters on white background. For games with a lot of graphics this may be nice, but for text handling, I find the inverse more comfortable for the eyes. Press CTRL-F2 to change the display from black on white to white on black and vice versa. Some ZX81 (machine coded) programmes do not allow you to stop them using Break (Shift-Space). On XTender, programmes can always be stopped using CTRL-ESC. This will actually cause a jump to an address in ROM where a RST 8 for error D is located, and hence the stack is cleared, the error message is displayed and you are back in Basic. Some programmes crash the ZX81 if you try this, as they may have messed around with the system variables, Basic area, screen or even with the ROM code. If CTRL-ESC causes a ZX81 `hangup', press CTRL-ALT-ESC. This restores the original ROM code and subsequently executes a RST 0. ANY programme can safely be aborted using CTRL-ALT-ESC. Note that the PEEK values of addresses 23 and 37 are preserved! For fun, enter the following commands: POKE 7687,85 { causes `rulers' } NEW { still rulers! } RAND USR 0 { no solution... } { cured! } Avoid using CTRL-ESC in the Basic editor or when CBI Trace is active. In general, CTRL-ESC should only be used when the normal Break is disabled. If you use CTRL-ESC in the normal ZX81 editor, it will lock keyboard operation. Press CTRL-ESC once more to get proper key response again. In the CBI editor, CTRL-ESC merely produces a space character, i.e. does not lock the keyboard. KEYBOARD COMPATIBILITY The ZX81 keyboard is totally different from the PC XT/AT keyboard. First of all, the ZX81 has only 40 keys. These are arranged according to the familiar QWERTY layout, yet - as you can imagine - 26 letter keys, 10 number keys, Shift, Space and NewLine (Enter) already make a grand total of 39 keys. The remaining 40th key is a full stop (`.'). So: all symbols are hidden under Shifted keys and (to make things more complex) in a non-PC-like fashion. The ZX81 works in UPPER CASE only, so in fact you have 39 Shift options (barring Shift itself, all keys can be Shifted, including Space and NewLine (Enter)). Symbols are really scattered around the keyboard (can you imagine using Shift-`B' for `*' and Shift-`U' for `$' !?!) and you will really need the help facility and some patience for locating the symbols. For UNshifted keys, the XTender maps almost the entire PC keyboard onto the ZX81 keyboard. Not only the 40 basic ZX81 keys, but also things like the Cursor Keys, BackSpace and the Numeric Pad are mapped. For example, if you press `Cursor Left', XTender will convert this to Shift-`5', the ZX81 equivalent. This makes editting (and sometimes also playing games) less strenuous. The central key of the numeric pad (`5') generates Shift-Enter, i.e. toggles Function mode. More special keys: the square brackets (`[..]') become normal brackets (`(..)') and the single forward quote gives the standard ZX81 double quote. The ESC key generates Shift-1 (Edit), i.e. brings the current cursored BASIC line in the editor. Also for SHIFTED keys, the emulator helps you a little bit. Pressing any one of the Shift keys will always give you the ZX81-Shifted symbol (like Shift-`U' for `$'). BUT, if you press ALT instead of SHIFT, you will get the PC-Shifted symbol, so you can press Alt-`4' to get the $tring sign. Some non-trivial ALTernatives are listed below: ALT-`6' gives `**' (instead of `^') ALT-`7' gives `AND' (instead of `&') ALT-`[' gives `<=' (instead of `{') ALT-`]' gives `>=' (instead of `}') ALT-`'' gives `""' (instead of `"') Note again, how the single forward quote (`'') is converted to a ZX81 double quote (`"') whereas the PC double quote is converted to a ZX81 quadruple quote (`""'). XTender effectively doubles quotes. Finally, if CAPSLOCK is on, the effect of Shift is INVERTED for ALL keys (not only the letter keys). So, pressing for example `B' with CAPSLOCK on gives `*', and Shift-`B' gives `B'. Note that this can be nice for some games which use the keys 5 through 8 for steering and do not allow you to press Shift. With CAPSLOCK on you can use the arrow keys of the keyboard! FILE MANAGEMENT Programmes can be SAVEd and LOADed in a format compatible to QZ (version 2.0 or higher), a QL fileserver for the ZX81 (first launched December 1989, version 2.0 introduced August 1991; nota bene: QL stands for Quantum Leap, a 68000-based multitasking computer, marketed by Sinclair in 1984). A detailed description regarding the possibilities of QZ is omitted here. If you are interested in QZ, please contact me in writing (address at the bottom of this document). The development of a QZ command interpreter for XTender is in preperation. To SAVE or LOAD a programme, just type SAVE "" LOAD "" which are the equivalents of the QZ commands SAVE:P:: LOAD:P:: The files are SAVEd to and LOADed from the drive/path which was default when XTender was started. Another drive/pathname canNOT be included in the filename. The SAVEd programmes appear as `.P' files on the default drive/path. LOADing a non-existing programme will NOT display any error. If you SAVE a programme which already existed, it will simply be overwritten without any user confirmation. Saving a file with a NAME of length zero results in the usual error F. Originally, QZ filenames were at most 12 characters long. On the PC, one is restricted to 8. So: only the first 8 characters of the SAVE/LOAD name will be used. Do NOT include INVERSE characters in the name, since these are used internally by the ZX81 to indicate the end of the filename. Commands will be passed to the QZ server of XTender in a SAVE or LOAD statement. The first character must be an asterisk (`*'). Currently, this can only be used for quitting XTender. Typing LOAD "*EXIT" or LOAD "*QUIT" will stop XTender and return to DOS. Any other command after the `*' will display error C (syntax error). PRINTER OUTPUT No printer driver is available as yet. This will be implemented in future versions. HIGH RESOLUTION In 1983, a first attempt to High Resolution on the ZX81 was presented when the High Resolution Toolkit by Richard Taylor was marketed. Later, companies like Software Farm produced several games in High Resolution. Taking a closer look at this 'High Resolution', one can easily see that it is not real Hi-Res: for the 256 bit patterns which are possible for 8 successive pixels, at most 128 are available, i.e. more than half of the patterns cannot be used. The result of this Semi Hi-Res may however still be quite satisfactory. As yet, no Hi-Res is supported by XTender. This will be implemented in future versions. Also, `real' hardware hi-res will be supported. ROM AND 8-16K AREA The ROM and 8-16k area are in fact also part of RAM, i.e. they are not POKE- protected. This can be nice for making slight changes in the ZX81 ROM or for using the 8-16k area for machine code utilities that can be loaded from disk. At startup, the 8-16k area contains an old verion of ZX-ASSEMBLER-2, a revised version of this well known Artic programme. In future version of XTender, this will be replaced by CORAL BASIC INTERPRETER (CBI version 7.0) The Assembler is started by typing: RAND USR 8192 No further comments on the use of the Assembler are given here. STOPPING There is only one legal way to end your XTender session. A ZX81 LOAD or SAVE command with an asterisk and some text return you to DOS, e.g. LOAD "*Q" CLOCK FREQUENCY The effective clock frequency can be determined in serveral ways. First of all, you can RUN a (long) BASIC programme which does not have any INPUT, INKEY$, RND, PAUSE or similar commands (i.e. execution time must be fully determinate and may not contain processor-independent loops). You can then compare the execution time on XTender to the time which this same programme requires on a ZX81. The ZX81 runs at 3.2 MHz in FAST mode and at 0.8 MHz in SLOW mode. Supposing a programme on XTender takes two times longer to execute than on the ZX81 in SLOW, the effective clock frequency is (0.8 MHz)/2 = 0.4 MHz. Another way to find the clock frequency is to use a machine code test loop, embracing a single instruction which is executed many (e.g. 65536) times. If you then count the number of frames needed (and subtract the number of frames needed for just the empty loop) you can get an idea of the clock frequency of that specific instruction, provided you know the number of T-cycles the Z80 would normally need for that same instruction. A very good estimate of the emulated processor speed can be obtained by LOADing the programme CLCKFREQ. This programme does some simple printing and plotting, but the final result is a reliable measure for the average speed. SLOWING DOWN OR SPEEDING UP On slow machines, the performance of the emulator can be increased by reducing the screen output frequency. This frequency is given by F = (18.2 Hz)/(PEEK 37) At startup, XTender tries to determine the best value for PEEK 37. POKEing a higher/lower value yourself can result in a significant increase/decrease of speed (test this with CLCKFREQ, see previous section). Note that a PEEK value of 0 hass the same effect as a PEEK value of 1. On fast machines the speed of the emulator can be reduced by POKEing address 23. The byte at this address is used as delay counter at each Z80 instruction. Default value is 1, which gives (practically) no delay. A higher value will quickly slow down emulation. Do not use zero: this effectively reacts as 256, so you end up with an extremely slow emulator. Example of SLOWDOWN on a 33 MHz 80386dx machine: PEEK 23 Speed Frequency 1 425% 3.40 MHz 2 362% 2.88 MHz 5 246% 1.96 MHz 10 160% 1.28 MHz 20 95% 0.76 MHz The slowdown only works if you are using XTENDERS (i.e. not with XTENDERF). The speeding up by POKEing address 37 works with both versions. Z80 EMULATION As far as I have been able to test, all Z80 instructions are emulated correctly: since the ZX81 ROM is the basis for XTender to function, the latter statement must be true. Also, many ZX81 programmes have been tested on XTender and all of them turned out to work without any problem! (These programmes include (commercially marketed) games and utilities in BASIC and in machine code!) Some brief remarks for Z80 freaks: * The Subtract flag of the Z80 flag-register (f) is NOT emulated. Many Z80 instructions alter this flag, but there is only one instruction which uses the result, viz. DAA. Since DAA is used only once in the ZX81 ROM (where it has been replaced by an equivalent non-standard Z80 instruction) and since proper emulation of the Subtract Flag reduces operation speed of XTender, I think this exclusion is a sensible decision. Note that, when XTender encounters a DAA instruction, it performs a `Decimal Adjust After Addition'. So, keep your fingers crossed! Programmes using DAA : --- Reversi (only the machine coded version) --- MCTT (Machine Code Testing Tool) --- Frogger If you should know of other programmes which use DAA, please tell me! * The IN instructions are all neglected, except for requests for port $FE, (the keyboard) and port $FB (the printer). Also, OUT instructions are neglected. Note, however, that the instructions IND, INDR, INI, INIR, OUTD, OTDR, OUTI and OTIR alter the registers BC and HL (and also (HL)'s) appropriately! * HALT waits for an interrupt. Interrupts are not emulated and therefore HALT is made equal to NOP. * Some instructions cannot be used for changing the ROM area (0-8k). These are: LD (HL),A LD (DE),A LD (HL),D LD (HL),E LDIR The reason for this is to protect the ROM against itself! The programmers of the ZX81 ROM have made use of the write-protection of the 0-8k area for simplifying their code (or is it a hitherto unknown bug of the ZX81 ROM ?). So, XTender (which has no write-protection in the ROM area) would alter its own code, which is (in general!) a bad thing. Therefore, the above instructions are emulated such that they have no effect in the first 8k of memory. Note that this also protects the ROM against a programme like MCODER-2, which does the same kind of nasty things to the ZX81 ROM-area... WRITING PROGRAMMES For the success of XTender and perhaps for a revival of the ZX81, I recommend authors of new programmes (either in machine code or in BASIC) to write their software such that it will run on both XTender and on the ZX81. As an example, you could perform nice tricks with XTender by POKEing its ROM, but that is not possible on the ordinary ZX81, i.e. INCOMPATIBLE! Please avoid such tricks or - if they are absolutely necessary - clearly include a message telling on which machine(s) the programme runs (ZX81, XTender, XTricator or the Atari Emulator). I also advise to use processor independent delay loops where necessary (mostly games and editors). Basically, these look like this: REPEAT SET CLOCK BEGIN PERFORM ACTION END REPEAT READ CLOCK UNTIL CERTAIN TIMELIMIT EXCEEDED FOREVER Programmes written this way are equally fast on every computer (unless the ACTION part takes more time than given by CERTAIN TIMELIMIT). In fact, several existing ZX81 programmes were really written this way and are consequently not sped up by a fast emulator (only decelerated by a slow one...)! For reading and setting the clock, make use of the system variable Frames. Frames is a two-byte number, decrementing at 50 Hz. Please note that (1) Frames is decremented in SLOW mode ONLY on the ZX81; (2) Frames is decremented in FAST AND SLOW mode on XTender; it is decremented by 2 or 3 each 55 ms, not by 1 each 20 ms. It is, however, properly synchronized. Also in BASIC programmes, use Frames (or PAUSE) instead of some empty FOR-NEXT loop. PROGRAMME TRANSPORTATION Some trouble is caused by the fact that ZX81 programmes were usually stored on tape instead of disk. Please write me for info on possible solutions! OTHER ZX81 EMULATORS The PC is not the only computer for which a ZX81 emulator has been written. An equivalent ZX81 emulator has also been written for the SINCLAIR QL and for the ATARI ST computers. The emulator for the Sinclair QL is called XTricator and is written by myself. It is completely compatible to XTender as far as file formats are concerned. This development of XTricator was started in 1989 and this programme offers far more possibilities than XTender (let alone the multitasking capabilities of the QL!). But, future versions of XTender will increasingly more resemble XTricator! I have no personal experience with the emulator written for the ATARI, but it seems that programmes running on that emulator can be LOADed directly into XTender/XTricator and RUN without problems. Note that the files with extension '81' on the ATARI emulator are compatible to the 'P' files of XTender and XTricator. It seems that the ATARI emulator has problems to LOAD files not SAVEd by the emulator itself (again, I have no personal experience). As far as I know, XTender/XTricator 'P' files cannot be converted to ATARI '81' files because of this 'sensitivity'. It is ofcourse the virtue of XTender and XTricator that it DOES work the other way round! WARRANTY If you come across a ZX81 programme which doesn't work on XTender and also doesn't fall in any of the "incompatibility catagories" discussed in this manual, please send me a copy of the programme on a 3.5" floppy. If XTender is to blame, you will receive a new (repaired!) version of XTender for free. ABOUT THE AUTHOR I was born in 1967 and bought my first computer (guess what, it was a ZX81!) in 1982. With no prior programming experience at all, I started writing simple Basic programmes. After about one year, it appeared to me that Basic just couldn't solve the problems I devised. So, I turned to Z80 machine code (with obliging help of Toni Baker; that is, of her book). A whole new world of possibilities opened up before my very eyes. High-speed compact code and access to all system utilities at lowest level, what else does a programmer need? Many Z80 programmes were born, and some of them were even published in international magazines. In 1987, I decided to buy a QL (during sales) and found this younger brother (sister?) just as interesting as the ZX81. It also gave me a good excuse for learning 68000 machine code. As I saw that less and less people were actually using the ZX81, I sought a way for elongating its existence. I thought that (amongst other things) a ZX81 emulator for the QL would be a good way to do so, and I started writing this programme in the end of 1989. My present-day occupation as an engineer of physics obliged me to buy an MS/DOS machine. In order to stay loyal to the absorbing machines made by Sinclair, I decided to write a ZX81 emulator for MS/DOS. The 8086 is very similar to the Z80, so I did not really have to learn a new language, only a new OS. By now, in 1991, you can judge the result of my efforts. I sincerely hope that many (former) ZX81 users will take some time to leap back in history and (re)enjoy the overwhelming simplicity of the 64k, 8-bit, 3.2 MHz Z80, black & white computer with 64x44 graphics resolution, which introduced over a million people worldwide (including myself) to the wonderful world of computing... XTENDER RELEASE HISTORY Version Date Remarks < 1.00 < November 1991 Illegal preliminary versions, likely to contain undocumented features and bugs. Use at your own risk or write me to become a registered XTender user. 1.00 > November 1991 First official release. FINAL NOTES All rights of XTender and this manual reserved by law (copyright); Consequently: UNAUTHORIZED copying, hiring and lending prohibited (please refer to section "Registration" for more details). Just to keep the lawyers happy: ZX81, QL and QDOS are registered trademarks of Sinclair Research Limited. For more information on XTender, XTricator, QZ, ZX-Assembler-2, Coral Basic Interpreter or ZX81 in general, do not hesitate to contact me at subjoined address in writing: Carlo Delhez, Emmastraat 3, 4651 BV Steenbergen, Netherlands. Thank you for reading the manual & for using XTender !! <*** End of File ***>